feat(acp): add machine stdio transport for Acepe by flazouh · Pull Request #2858 · tailcallhq/forgecode

flazouh · 2026-04-05T20:10:19Z

Abstract

This PR adds a real forge machine stdio entrypoint backed by Forge's ACP stdio transport. It is primarily for our app, Acepe, which needs to launch Forge from a stable CLI surface without depending on an unpublished feature branch.

Product Context

Acepe is our desktop app for running and managing coding agents across providers and protocols.

Product links:

Problem

Acepe integrates Forge as an installable local provider. That integration needed a released Forge command that can:

start a machine-oriented stdio session from the public CLI
speak ACP over stdio instead of only parsing a placeholder command
be launched by Acepe as a normal installed binary

Before this change, the relevant command path was missing on main. We could add parser coverage for forge machine stdio, but that would still leave the command non-functional at runtime, which does not unblock Acepe.

Solution

This change wires the machine-facing CLI entrypoint all the way through to a working ACP stdio server:

adds machine stdio as a first-class top-level CLI command
routes the CLI command through forge_main into a dedicated stdio runner
extends the public API surface with acp_start_stdio() so the transport can be started through the current app/service stack
ports the ACP stdio transport implementation into forge_app
adds the required ACP dependency wiring in the workspace and app manifests
preserves parser-level coverage and adds transport-adjacent verification

The intent is to keep the public invocation simple while making the underlying server path real and launchable by external applications.

ASCII Schemas

Before

+---------+              +------------------------+
| Acepe   | -- spawn --> | forge machine stdio    |
| app     |              | on forge main          |
+---------+              +-----------+------------+
                                    |
                                    v
                         +------------------------+
                         | missing / non-working  |
                         | machine transport      |
                         +------------------------+
                                    |
                                    v
                             integration blocked

After

+---------+              +------------------------+
| Acepe   | -- spawn --> | forge machine stdio    |
| app     |              | stable CLI entrypoint  |
+---------+              +-----------+------------+
                                    |
                                    v
                         +------------------------+
                         | forge_main acp_runner  |
                         +-----------+------------+
                                    |
                                    v
                         +------------------------+
                         | forge_api::            |
                         | acp_start_stdio()      |
                         +-----------+------------+
                                    |
                                    v
                         +------------------------+
                         | forge_app ACP stdio    |
                         | transport + adapter    |
                         +-----------+------------+
                                    |
                                    v
                         +------------------------+
                         | Acepe <-> Forge over   |
                         | ACP / stdio            |
                         +------------------------+

Ownership Boundary

Acepe responsibilities
----------------------
- install Forge
- discover provider
- spawn `forge machine stdio`
- speak ACP over stdio

Forge responsibilities
----------------------
- expose stable machine CLI
- initialize ACP transport
- adapt ACP requests into Forge services
- stream ACP responses back over stdio

Why This Is For Acepe

Acepe needs Forge to expose a stable, installable machine transport from main so our desktop app can launch Forge directly as a provider. This PR moves that capability into the open-source Forge repo so Acepe no longer has to depend on branch-specific or unpublished transport work.

Files Of Interest

crates/forge_main/src/cli.rs
crates/forge_main/src/ui.rs
crates/forge_main/src/acp_runner.rs
crates/forge_api/src/api.rs
crates/forge_api/src/forge_api.rs
crates/forge_app/src/acp_app.rs
crates/forge_app/src/acp/

Verification

I verified the change with:

env PROTOC=/tmp/protoc-28.3/bin/protoc cargo test --manifest-path /Users/alex/Documents/forgecode/Cargo.toml -p forge_main machine_stdio
env PROTOC=/tmp/protoc-28.3/bin/protoc cargo test --manifest-path /Users/alex/Documents/forgecode/Cargo.toml -p forge_app acp
env PROTOC=/tmp/protoc-28.3/bin/protoc cargo test --manifest-path /Users/alex/Documents/forgecode/Cargo.toml -p forge_app acp::conversion

Notes

protoc was not available on PATH in the local environment, so verification used a staged temporary binary.
The PR is intentionally focused on exposing the stdio ACP transport through the current CLI/API layers rather than reworking unrelated provider or UI behavior.

Expose a machine stdio entrypoint in Forge and route it through a real ACP stdio transport so Acepe can launch Forge as an installable provider instead of depending on an unpublished branch. Co-Authored-By: ForgeCode <noreply@forgecode.dev>

CLAassistant · 2026-04-05T20:11:52Z

All committers have signed the CLA.

graphite-app · 2026-04-05T20:13:43Z

+        fn acp_start_stdio(&self) -> impl std::future::Future<Output = Result<()>> + Send {
+            self.called.store(true, Ordering::SeqCst);
+            async { Ok(()) }
+        }


The test implementation has incorrect async behavior. The self.called.store() executes immediately when the future is created, not when it's awaited. This means the test doesn't accurately verify that the async function is actually executed.

fn acp_start_stdio(&self) -> impl std::future::Future<Output = Result<()>> + Send { let called = self.called.clone(); async move { called.store(true, Ordering::SeqCst); Ok(()) } }

Suggested change

fn acp_start_stdio(&self) -> impl std::future::Future<Output = Result<()>> + Send {

self.called.store(true, Ordering::SeqCst);

async { Ok(()) }

}

fn acp_start_stdio(&self) -> impl std::future::Future<Output = Result<()>> + Send {

let called = self.called.clone();

async move {

called.store(true, Ordering::SeqCst);

Ok(())

}

}

Spotted by Graphite

Is this helpful? React 👍 or 👎 to let us know.

- Replace unbounded notification channel with bounded (1024) to apply backpressure when the client stalls - Add per-session model override to prevent concurrent sessions from interfering with each other - Replace From<Error> impl with explicit into_acp_error() per project guidelines - Extract classify_mcp_tool() and convert to free functions, removing the unnecessary ToolOutputConverter struct - Validate MCP server names (length, charset) to prevent injection - Add MAX_BLOB_SIZE (50 MB) guard on base64-decoded resources - Add I/O timeout (5 min) and graceful shutdown drain (5 s) to prevent indefinite hangs - Track cancellation via AtomicBool across loop iterations - Log warnings instead of silently ignoring reload/config errors - Add tests for tool kind mapping, file extraction, and edge cases Co-Authored-By: ForgeCode <noreply@forgecode.dev>

The store ran eagerly on function call, not when the future was awaited. Move it into the async block so the test actually verifies that the caller awaits the returned future. Co-Authored-By: ForgeCode <noreply@forgecode.dev>

github-actions · 2026-04-13T05:06:06Z

Action required: PR inactive for 5 days.
Status update or closure in 10 days.

github-actions · 2026-04-24T13:34:10Z

PR closed after 10 days of inactivity.

flazouh · 2026-04-24T17:08:49Z

@amitksingh1490 thanks for looking at this for our user requesting forge integration !

amitksingh1490 · 2026-04-26T03:33:48Z

@flazouh could you please resolve the conflicts would love to integrate this. We are thinking we should introduce a beta feature flag till the time we stablise this and then once its stable expose it to everyone.
Let me know your thoughts and lets connect on discord to discuss how to test this?

github-actions · 2026-05-01T05:18:44Z

Action required: PR inactive for 5 days.
Status update or closure in 10 days.

flazouh · 2026-05-03T23:35:06Z

with pleasure, i'm flaze9 on discord

Co-Authored-By: ForgeCode <noreply@forgecode.dev>

github-actions · 2026-05-09T01:37:24Z

Action required: PR inactive for 5 days.
Status update or closure in 10 days.

ssfdust · 2026-05-10T05:48:22Z

Great work!

I am testing the acp feature with the neovim plugin, and I found some critical bugs. I don't know how Acepe works, but it can't work with my neovim plugin. The following are the fixes advised by forge(model deepseek-v4-pro).

Outdated Fixes

# Summary

`forge machine stdio` fails to connect when spawned as subprocess by agentic.nvim

Background

agentic.nvim spawns forge machine stdio with stdin/stdout pipes to communicate via the Agent Communication Protocol (JSON-RPC over stdio). However, the forge process never responds to the initialize request, causing agentic.nvim to report that it "cannot parse" the process.

Root Cause

In crates/forge_main/src/main.rs (around line 95), there is a stdin pre-read logic:

if !std::io::stdin().is_terminal() {
    let mut stdin_content = String::new();
    std::io::stdin().read_to_string(&mut stdin_content)?;
    // ...
}

When forge machine stdio is spawned as a subprocess:

Stdin is a pipe (not a TTY), so is_terminal() returns false
read_to_string() blocks indefinitely waiting for EOF
But agentic.nvim keeps the write end of the pipe open for ongoing bidirectional JSON-RPC messages
The process never reaches the ACP server initialization code

The code already had an exclusion for forge select (which also needs stdin interactivity), but machine stdio was missing from the exclusion list.

Fix

Add Machine to the stdin pre-read exclusion list (main.rs:96-99):

let needs_stdin = matches!(
    cli.subcommands,
    Some(TopLevelCommand::Select(_)) | Some(TopLevelCommand::Machine(_))
);
if !needs_stdin && !std::io::stdin().is_terminal() {
    // read piped input
}

Secondary Issue: Panic Hook Pollutes Stdout

In crates/forge_main/src/main.rs, the panic hook uses println! which writes to stdout:

panic::set_hook(Box::new(|panic_info| {
    println!("{}", TitleFormat::error(message.to_string()).display());
}));

If forge panics during initialization (e.g., corrupted config file, missing dependencies), the error message is written to stdout as plain text, which corrupts the ACP JSON-RPC data stream. This should use eprintln! (stderr) instead.

Secondary Issue: Sandbox Worktree Messages Pollute Stdout

In crates/forge_main/src/sandbox.rs (lines 72 and 128), worktree creation status messages are written to stdout:

// line 72
println!("{}", TitleFormat::info("Worktree [Reused]").sub_title(...).display());
// line 128
println!("{}", TitleFormat::info("Worktree [Created]").sub_title(...).display());

Sandbox::create() runs in main.rs before UI::init(), so when forge machine stdio --sandbox xxx is invoked, plain text is written to stdout before the ACP server starts. This should use eprintln! (stderr) instead, since stderr is a separate file descriptor from the ACP JSON-RPC transport channel.

How to Reproduce

Run any ACP client that spawns forge machine stdio with stdin/stdout pipes and sends a JSON-RPC initialize request. The forge process will hang indefinitely and never respond.

Suggested Actions

Keep the Machine subcommand in the stdin pre-read exclusion list
Change println! to eprintln! in the panic hook
Change println! to eprintln! in sandbox.rs for worktree status messages
Consider adding an integration test that verifies forge machine stdio responds to initialize when stdin is a pipe (non-TTY)

EDIT:

I add a --stdin argment to the machine stdio

Extracts independently-mergable fixes from the ongoing ACP work (tailcallhq#2858) that can land on main immediately. Three classes of fix: 1. stdin pre-read encapsulation (cli.rs, main.rs) Add Cli::uses_stdin() method that centralizes the decision of which subcommands own stdin. Subcommands opt in via uses_stdin() rather than having the startup pipeline guess from a hardcoded exclusion list. This makes it easy to add new stdin-consuming subcommands (e.g. an ACP stdio server) without touching the startup logic. 2. Tool output leaking to stdout (context.rs, tool_executor.rs) Shell tool execution streamed raw output to io::stdout(), corrupting the ACP JSON-RPC stream. Add silent: bool field on ToolCallContext (the correct home for per-invocation runtime flags). Default false; ACP sets .silent(true) to route output to io::sink() instead. 3. Stderr vs stdout discipline (main.rs, sandbox.rs) Panic hook and worktree status messages used println! which writes to stdout. Changed to eprintln! (stderr) to avoid contaminating structured transport channels. Co-authored-by: ForgeCode <noreply@forgecode.dev> Co-authored-by: DeepSeek <deepseek@deepseek.com> Signed-off-by: ssfdust <ssfdust@gmail.com>

Extracts independently-mergable fixes from the ongoing ACP work (tailcallhq#2858) that can land on main immediately. Three classes of fix: 1. stdin pre-read encapsulation (cli.rs, main.rs) Add Cli::uses_stdin() method that centralizes the decision of which subcommands own stdin. Subcommands opt in via uses_stdin() rather than having the startup pipeline guess from a hardcoded exclusion list. This makes it easy to add new stdin-consuming subcommands (e.g. an ACP stdio server) without touching the startup logic. 2. Tool output leaking to stdout (context.rs, tool_executor.rs) Shell tool execution streamed raw output to io::stdout(), corrupting the ACP JSON-RPC stream. Add silent: bool field on ToolCallContext (the correct home for per-invocation runtime flags). Default false; ACP sets .silent(true) to route output to io::sink() instead. 3. Stderr vs stdout discipline (main.rs, sandbox.rs) Panic hook and worktree status messages used println! which writes to stdout. Changed to eprintln! (stderr) to avoid contaminating structured transport channels. Signed-off-by: ssfdust <ssfdust@gmail.com> Co-authored-by: ForgeCode <noreply@forgecode.dev> Co-authored-by: DeepSeek <deepseek@deepseek.com>

Extracts independently-mergable fixes from the ongoing ACP work (tailcallhq#2858) that can land on main immediately. Three classes of fix: 1. stdin pre-read encapsulation (cli.rs, main.rs) Add Cli::uses_stdin() method that centralizes the decision of which subcommands own stdin. Subcommands opt in via uses_stdin() rather than having the startup pipeline guess from a hardcoded exclusion list. This makes it easy to add new stdin-consuming subcommands (e.g. an ACP stdio server) without touching the startup logic. 2. Tool output leaking to stdout (context.rs, tool_executor.rs) Shell tool execution streamed raw output to io::stdout(), corrupting the ACP JSON-RPC stream. Add silent: bool field on ToolCallContext (the correct home for per-invocation runtime flags). Default false; ACP sets .silent(true) to route output to io::sink() instead. 3. Stderr vs stdout discipline (main.rs, sandbox.rs) Panic hook and worktree status messages used println! which writes to stdout. Changed to eprintln! (stderr) to avoid contaminating structured transport channels. Signed-off-by: ssfdust <ssfdust@gmail.com> Co-authored-by: ForgeCode <noreply@forgecode.dev> Co-authored-by: DeepSeek <deepseek-ai@deepseek.com>

Happily-Coding · 2026-05-13T20:27:27Z

Awesome to see you are working on it.
I wonder if the command should be renamed to acp though. For reference

Opencode's command is :opencode acp
gemini's command is : gemini --acp

Extracts independently-mergable fixes from the ongoing ACP work (tailcallhq#2858) that can land on main immediately. Three classes of fix: 1. stdin pre-read encapsulation (cli.rs, main.rs) Add Cli::uses_stdin() method that centralizes the decision of which subcommands own stdin. Subcommands opt in via uses_stdin() rather than having the startup pipeline guess from a hardcoded exclusion list. This makes it easy to add new stdin-consuming subcommands (e.g. an ACP stdio server) without touching the startup logic. 2. Tool output leaking to stdout (context.rs, tool_executor.rs) Shell tool execution streamed raw output to io::stdout(), corrupting the ACP JSON-RPC stream. Add silent: bool field on ToolCallContext (the correct home for per-invocation runtime flags). Default false; ACP sets .silent(true) to route output to io::sink() instead. 3. Stderr vs stdout discipline (main.rs, sandbox.rs) Panic hook and worktree status messages used println! which writes to stdout. Changed to eprintln! (stderr) to avoid contaminating structured transport channels. Signed-off-by: ssfdust <ssfdust@gmail.com> Co-authored-by: ForgeCode <noreply@forgecode.dev> Co-authored-by: DeepSeek <deepseek-ai@deepseek.com>

luandro · 2026-05-20T03:09:50Z

Any advances on this? Seems like this got stale,

amitksingh1490 · 2026-05-20T06:10:32Z

+use super::error::{Error, Result};
+
+/// Maximum number of buffered session notifications before backpressure.
+const NOTIFICATION_CHANNEL_CAPACITY: usize = 1024;


move this to config

amitksingh1490 · 2026-05-20T06:16:33Z

        app.execute(data_parameters).await
    }

+    async fn acp_start_stdio(&self) -> Result<()> {


This should not be part of api, instead it should be build on top of api

github-actions · 2026-05-25T17:34:25Z

Action required: PR inactive for 5 days.
Status update or closure in 10 days.

flazouh · 2026-05-27T11:41:40Z

Will address those comments ASAP, guys !

github-actions Bot added the type: feature Brand new functionality, features, pages, workflows, endpoints, etc. label Apr 5, 2026

graphite-app Bot reviewed Apr 5, 2026

View reviewed changes

flazouh force-pushed the feat/machine-stdio-acp branch from a2e5e58 to 8fe513f Compare April 5, 2026 22:58

fix(test): move mock assertion inside async block

4b014b5

The store ran eagerly on function call, not when the future was awaited. Move it into the async block so the test actually verifies that the caller awaits the returned future. Co-Authored-By: ForgeCode <noreply@forgecode.dev>

github-actions Bot added the state: inactive No current action needed/possible; issue fixed, out of scope, or superseded. label Apr 13, 2026

github-actions Bot closed this Apr 24, 2026

amitksingh1490 reopened this Apr 24, 2026

github-actions Bot removed the state: inactive No current action needed/possible; issue fixed, out of scope, or superseded. label Apr 24, 2026

amitksingh1490 enabled auto-merge (squash) April 24, 2026 17:44

amitksingh1490 disabled auto-merge April 24, 2026 17:44

github-actions Bot added the state: inactive No current action needed/possible; issue fixed, out of scope, or superseded. label May 1, 2026

Merge upstream/main into feat/machine-stdio-acp

8db5866

github-actions Bot removed the state: inactive No current action needed/possible; issue fixed, out of scope, or superseded. label May 4, 2026

flazouh force-pushed the feat/machine-stdio-acp branch from de35545 to 8db5866 Compare May 4, 2026 00:45

test(acp): expand machine stdio coverage

80193f9

Co-Authored-By: ForgeCode <noreply@forgecode.dev>

github-actions Bot added the state: inactive No current action needed/possible; issue fixed, out of scope, or superseded. label May 9, 2026

github-actions Bot removed the state: inactive No current action needed/possible; issue fixed, out of scope, or superseded. label May 10, 2026

ssfdust mentioned this pull request May 11, 2026

chore: extract ACP stdio transport pre-patch #3310

Closed

luandro mentioned this pull request May 13, 2026

[Feature]: Support ACP (Agent Client Protocol) #2968

Open

2 tasks

Merge branch 'main' into feat/machine-stdio-acp

136d898

amitksingh1490 reviewed May 20, 2026

View reviewed changes

github-actions Bot added the state: inactive No current action needed/possible; issue fixed, out of scope, or superseded. label May 25, 2026

github-actions Bot removed the state: inactive No current action needed/possible; issue fixed, out of scope, or superseded. label May 27, 2026

Conversation

flazouh commented Apr 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Abstract

Product Context

Problem

Solution

ASCII Schemas

Before

After

Ownership Boundary

Why This Is For Acepe

Files Of Interest

Verification

Notes

Uh oh!

CLAassistant commented Apr 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

graphite-app Bot Apr 5, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot commented Apr 13, 2026

Uh oh!

github-actions Bot commented Apr 24, 2026

Uh oh!

flazouh commented Apr 24, 2026

Uh oh!

amitksingh1490 commented Apr 26, 2026

Uh oh!

github-actions Bot commented May 1, 2026

Uh oh!

flazouh commented May 3, 2026

Uh oh!

github-actions Bot commented May 9, 2026

Uh oh!

ssfdust commented May 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

forge machine stdio fails to connect when spawned as subprocess by agentic.nvim

Background

Root Cause

Fix

Secondary Issue: Panic Hook Pollutes Stdout

Secondary Issue: Sandbox Worktree Messages Pollute Stdout

How to Reproduce

Suggested Actions

Uh oh!

Happily-Coding commented May 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

luandro commented May 20, 2026

Uh oh!

amitksingh1490 May 20, 2026

Choose a reason for hiding this comment

Uh oh!

amitksingh1490 May 20, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot commented May 25, 2026

Uh oh!

flazouh commented May 27, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

flazouh commented Apr 5, 2026 •

edited

Loading

CLAassistant commented Apr 5, 2026 •

edited

Loading

ssfdust commented May 10, 2026 •

edited

Loading

`forge machine stdio` fails to connect when spawned as subprocess by agentic.nvim

Happily-Coding commented May 13, 2026 •

edited

Loading